# kind: Trigger

Конфигурация предназначена для описания правил реагирования на соответвующий шаблон для выполнения мутации ресурса.

Теперь следует реализовать правила, по которым будет вызываться инжектирование описанного ранее sidecar.

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: triggername
  namespace: KBLT_NAMESPACE
spec:
  mutationConfigs:
    - name: mutation-config-test     
      match:
        serviceAccount: .*istio-operator.* 
        kinds:
          - kinds: # список ресурсов, которые мутируются
              - Deployment
            apiGroups:
              - '*'
        namespaceSelector:
          matchExpressions:
            - key: key
              operator: In
              values:
                - value
        annotationNamespace: kblt.io 
        annotationTrigger: mutation
        labelSelector: 
          matchExpressions:
            - key: key
              operator: In
              values:
                - value
        name: some-name # завязка на имени мутируемого ресурса. Если поле отсутствует, то расмматриваются все наименования ресурса
        excludedNamespaces: # cписок исключенных namespace (поддерживает регулярные выражения)
          - namesapce-1
          - namespace-2
        namespaces: # cписок наблюдаемых namespace (поддерживает регулярные выражения)
          - namesapce-*
          - namespace2-popo
        scope: * (Cluster/Namespaced) # идентификатор ресурса кластерный, либо namespace local
        operations: # операции (Create - object, UPDATE - object/oldObject), DELETE - oldObject)
          - CREATE  
        mutationConditions: # условия для проведения мутации объекта
          - path: spec.containers[?@name == `istio-proxy`]
            condition: MustExist
          - path: contains(spec.containers[?@name == `istio-proxy`].image, `@sha_something`)
            condition: MustNotExist
 
      templateRefs:                                     
        - <namespace>/template-mutation-deployment      
      updateStrategy: merge                             
```

| Поле                                | Назначение                                                                                          |
|-------------------------------------|-----------------------------------------------------------------------------------------------------|
| [mutationConfigs](#mutationConfigs) | Список условий, при которых должен выполниться мутирующий webhook, а так же ресурсы sidecar/volumes |

## mutationConfigs

Список условий, при которых должен выполниться мутирующий webhook, а так же ресурсы sidecar/volumes 

| Поле            | Назначение                                                                                                                                                                                                                                                                                                                                                                                 |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name            | Уникальное наименование условия (конструкция аннотации)                                                                                                                                                                                                                                                                                                                                    |
| updateStrategy  | Стратегия, по которой будет производиться мутирование. Возможно указание одного из значений:<br> 1. replace - описанный шаблон в "kind: Template" перезапишет всю спецификацию контейнера/объекта мутации <br> 2. merge (по умолчанию) - описанный шаблон в "kind: Template" частично перезапишет мутируемый объект, в зависимости от уровня различий между шаблоном и мутируемым ресурсом |
| [match](#match) | Правила выбора запросов для проведения мутаций. Если указанные в этой секции условия выполнены – мутация будет производится. Другими словами это правила, на которые реагирует «kind: Trigger»                                                                                                                                                                                             |
| templateRefs    | Список шаблонов которые будут применены при мутации (формат: - <имя проекта шаблона>/<имя шаблона «kind: Template»>)                                                                                                                                                                                                                                                                       |


## match

Правила выбора запросов для проведения мутаций. Если указанные в этой секции условия выполнены – мутация будет производится. Другими словами это правила, на которые реагирует «kind: Trigger»

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: my-gateway
  namespace: some-namespace
spec:
  mutationConfigs:
    - name: mutation-config-test
      match:
        kinds:
          - kinds:
              - Pod
            apiGroups:
              - '*'
        annotationSelector:
          matchExpressions:
            - key: kblt.io/mutation-test
              operator: In
              values:
                - enabled
        labelSelector:
          matchExpressions:
            - key: find-pod
              operator: In
              values:
                - fedmesh-mutator
        name:
          regex: mutating-deployment-test*
        scope: Namespaced
        operations:
          - CREATE
        matchConditions:
          object:
            - path: spec.containers[?@.name == `to-test-latte-1`]
              condition: MustExist
```

| Поле                                      | Назначение                                                                                                                    |
|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| [kinds](#kinds)                           | Перечень типов ресурсов, которые разрешены к мутации                                                                          |
| [userInfo](#userInfo)                     | Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект (type: validation)                           |
| [name](#name)                             | Наименование объекта, по которому будет происходить мутация. Если нет этого поля, то проверка по имени обекта не производится |
| scope                                     | Идентификатор принадлежности ресурса к scope <br> Возможные значения: '*', Namespaced, Cluster                                |
| [namespaceSelector](#namespaceSelector)   | Метка (label) на namespace, в рамках которых будет происходить мутация                                                        |
| excludedNamespaces                        | Список исключенных namespace, по которым не будет происходить мутация                                                         |
| namespaces                                | Список namespace, по которым будет происходить мутация                                                                        |
| [operations](#operations)                 | Операции над объектом, по которым будет происходить мутация (CREATE/UPDATE/DELETE)                                            |
| [labelSelector](#labelselector)           | Метка (label) на объекте, по которому будет происходить мутация                                                               |
| [annotationSelector](#annotationSelector) | Аннотация на объекте, по которому будет происходить мутация                                                                   |


## kinds
Является обязательным полем, в котором указывается список типов ресурсов, которые разрешены к мутации.

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        kinds:                                          
          - kinds:
              - '*'         # разрешаем все типы ресурсов
            apiGroups:
              - '*'         # разрешаем все apiVersion ресурсов
        ...
```

| Поле      | Назначение                                          |
|-----------|-----------------------------------------------------|
| kinds     | Cписок типов ресурсов, которые разрешены к мутации  |
| apiGroups | Cписок версий ресурсов, которые разрешены к мутации |


## userInfo

Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект (type: validation)

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        userInfo:
          usernameRegex: .* # разрешение для любого username ресурса

          или

          username: name_user # разрешение для ресурса с "username: name_user"
        ...
```

| Поле          | Назначение                                                                                   |
|---------------|----------------------------------------------------------------------------------------------|
| username      | Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект             |
| usernameRegex | Регулярное выражение для ServiceAccount/User. Конкретизация пользователя, кто создает объект |


## name

Наименование объекта, по которому будет происходить мутация

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        name:
          value: testing-matc

          или

          regex: '.*istio\..*io'
        ...
```

| Поле               | Назначение                                            |
|--------------------|-------------------------------------------------------|
| value              | Наименование валидируемого ресурса                    |
| regex              | Регулярное выражение для имени валидируемого ресурса  |

Тип описания правил "value" находится в приоритете над типом "regex", поэтому при описании обоих полей будет рассматриваться только те правила, которые описаны в поле "value". Рекоммендуется использовать один тип правил: либо "value", либо "regex".


## namespaceSelector

Если в рамках AdmissionReview отсутствует request.object.metadata.namespace, то проверка считается успешной, проверяются следующие условия в секции match. Если поле отсутствует, то проверка namespace не происходит и проверяются следующие условия в секции match.

Метка (label) на namespace, в рамках которых будет происходить мутация

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        namespaceSelector:
          matchExpressions:
            - key: label-for-validation
              operator: In
              values:
                - value-1
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |


## operations

- CREATE соответствует операции создания объекта. При создании в поле matchConditions передается информация о мутации только нового объекта (object), поле oldObject пустое

- UPDATE соответствует операции обновления объекта. При обновлении в поле matchConditions передается информация о мутации текущего объекта (oldObject) и объекта (object) после мутации

- DELETE соответствует операции удаления объекта. При удалении в поле matchConditions передается информация о старом объекте (oldObject), поле object пустое. Причем в этом случае не происходит этапа мутирования, так как объек все равно будет удален и лишние изменения объекта не требуются


## labelSelector

Метка (label) на объекте, по которому будет происходить мутация. Если поле отсутствует, то проверка label не происходит и проверяются следующие условия в секции match.

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        labelSelector:
          matchExpressions:
            - key: label-for-validation
              operator: NotIn
              values:
                - 'false'
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |



## annotationSelector

Аннотация на объекте, по которому будет происходить мутация. Если поле отсутствует, то проверка label не происходит и проверяются следующие условия в секции match.

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        annotationSelector:
          matchExpressions:
            - key: test.myannot
              operator: DoesNotExist
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |




## matchConditions

Условия на проверку старого/нового состояния конфигурации

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-mutations-rule
spec:   
  mutationConfigs:     
    - name: mutation1
      match:
        ...
        matchConditions:
          object:
            - path: spec.template.spec.containers[? @.name == `name1`]
              condition: MustExist
          oldObject:
            - path: spec.containers[? @.name == `name2`]
              condition: MustExist
            - path: spec.containers[? @.name == `name3`]
              condition: MustNotExist
        ...
```

| Поле                      | Назначение                                                                          |
|---------------------------|-------------------------------------------------------------------------------------|
| [oldObject](#(old)Object) | Секция для проверки бывшей реализации CRD для принятия решения о проведении мутации |
| [object](#(old)Object)    | Секция для проверки новой реализации CRD для принятия решения о проведении мутации  |

## (old)Object

Секция для проверки бывшей/новой реализации CRD для принятия решения о проведении мутации 

| Поле      | Назначение                                                                                                                                                                                                                                                         |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| path      | Конкретизация секции, формата [JMESPath](https://jmespath.org/) query                                                                                                                                                                                              |
| condition | enum: <br>1. MustExist - ожидаемый результат "true" в рамках обработки секции path (наличие любого текста, либо boolean 'true') <br> 2. MustNotExist - ожидаемый результат "false" в рамках обработки секции path (отсутствие любого текста, либо boolean 'false') |


# SideEffect

Для реализации логики SideEffect конфигурация будет иметь немного иной вид. Главным отличием является наличие секции «sideEffectConfig».

```yaml
kind: Trigger
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: triggername
  namespace: KBLT_NAMESPACE
spec:
  sideEffectConfigs:
    - match:
        kinds:
          - apiGroups:
              - ''
            kinds:
              - Pod
        operations:
          - CREATE
        labelSelector:
          matchExpressions:
            - key: key
              operator: In
              values:
                - enabled
      name: sideeffect-example
      templateRefs:
        - KBLT_NAMESPACE/sideeffect-example-1
        - KBLT_NAMESPACE/sideeffect-example-2
```

В данном примере, если пользователь публикует на кластере «kind: Pod», то конфигурация «kind: Trigger» среагирует на создание и перейдет к шаблонам «kind: Template» из templateRefs. Пример «kind: Template», который может быть реализован:

```yaml
kind: Template
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: sideeffect-example-1
  namespace: KBLT_NAMESPACE
spec:
  kind: TriggerInstance
  apiVersion: some_version
  data: |-
    kind: TriggerInstance
    apiVersion: some_version
    metadata:
      name: sideeffect-example-1
      annotations: 
        KBLT_NAMESPACE/triggername: enabled
    spec:
      data: data
```

В результате работы SideEffect создастся «kind: TriggerInstance». Далее, по логике креации, в кластере на только что опубликованный «kind: TriggerInstance» среагирует «kind: Trigger» - будет создан ресурс по описанию из data. 